﻿using System.Collections.Generic;

namespace Com.FastSearch.SharePoint.Interfaces
{
    /// <summary>
    /// A navigator enumerates the available values of a field or xml scope in a search result,
    /// and enables the results to be narrowed by only showing results with a particular value
    /// for that field.
    /// <p/>
    /// This interface defines the navigator, while the avaiable values are defined by the
    /// <see cref="IESPNavigatorItem"/> interface.
    /// </summary>
    public interface IESPNavigator
    {
        /// <summary>
        /// The internal name of the navigator.
        /// </summary>
        string Name { get; }

        /// <summary>
        /// The name of the navigator as it should be displayed to users.
        /// </summary>
        string DisplayName { get; }

        /// <summary>
        /// The unit of the navigator, e.g. kB for a size-navigator.
        /// </summary>
        string Unit { get; }

        /// <summary>
        /// The number of documents scanned when aggregating the navigator.
        /// </summary>
        int HitsUsed { get; }

        /// <summary>
        /// The number of items available for the navigator.
        /// </summary>
        int ItemCount { get; }

        /// <summary>
        /// The items of the navigator that can be used to drill down in the results.
        /// </summary>
        /// <seealso cref="AppliedNavigatorItems"/>
        IEnumerable<IESPNavigatorItem> NavigatorItems { get; }

        /// <summary>
        /// The items of the navigator that are already used to drill down in the results.
        /// </summary>
        /// <seealso cref="NavigatorItems"/>
        IEnumerable<IESPNavigatorItem> AppliedNavigatorItems { get; }
    }

    /// <summary>
    /// This interface defines a single point of drill-down for an <see cref="IESPNavigator"/>.
    /// </summary>
    public interface IESPNavigatorItem
    {
        /// <summary>
        /// The name of the field the value is taken from.
        /// </summary>
        string FieldName { get; }

        /// <summary>
        /// The actual value to be used for filtering the search result to narrow them. Not
        /// to be presented to users, <see cref="DisplayValue"/> gives a human readable value.
        /// </summary>
        string FilterValue { get; }

        /// <summary>
        /// The value of the navigator item, as it should be presented to the user.
        /// </summary>
        string DisplayValue { get; }

        /// <summary>
        /// The number of hits in the result set that matches this item's value.
        /// </summary>
        int ResultCount { get; }

        /// <summary>TODO: update with info about split
        /// The string that must be included in the <code>navigation</code> search parameter
        /// for the navigator item to be applied, or to <code>scopenavigation</code> for
        /// scope navigators.
        /// </summary>
        /// <param name="scope">The scope if a scope navigator, otherwise null</param>
        /// <param name="split">The character to use between the fields</param>
        /// <returns>The parameter for doing drill-down</returns>
        string GetNavigationParam(string scope, char split);
    }
}
